package com.naza.rpc.circuitBreaker;

/**
 * 熔断器 当服务端出现问题时，直接返回mock值 A CircuitBreaker manages the state of a backend
 * system. It is notified on the result of all attempts to communicate with the
 * backend, via the {@link #recordSuccess} and {@link #recordFailure} methods.
 * Before communicating with the backend, the respective connector must obtain
 * the permission to do so via the method {@link #isCallPermitted()}.
 *
 * @author yl
 */
public interface CircuitBreaker {
    /**
     * 请求是否允许 Requests permission to call this circuitBreaker's backend.
     *
     * @return boolean whether a call should be permitted
     */
    boolean isCallPermitted();

    /**
     * 记录一次失败调用 Records a failed call. This method must be invoked after a
     * failed call.
     *
     * @param throwable
     *            The throwable which must be recorded
     */
    void recordFailure(Throwable throwable);

    /**
     * 记录一次失败调用 Records a failed call. This method must be invoked after a
     * failed call.
     */
    void recordFailure();

    /**
     * 记录一次成功调用 Records a successful call. This method must be invoked after a
     * successful call.
     */
    void recordSuccess();

    /**
     * 递增当前执行总数 increment concurrent executions counter.
     */
    void incCurrentExecutions();

    /**
     * 递减当前执行总数 decrement concurrent executions counter.
     */
    void decCurrentExecutions();

    /**
     * 获取当前执行总数 get concurrent executions count.
     *
     * @return count
     */
    long getCurrentExecutions();

    /**
     * 获取熔断器名称 Get the name of this CircuitBreaker
     *
     * @return the name of this CircuitBreaker
     */
    String getName();

    /**
     * 获取熔断器状态 Get the state of this CircuitBreaker
     *
     * @return the state of this CircuitBreaker
     */
    State getState();

    /**
     * 获取熔断器配置 Get the CircuitBreakerConfig of this CircuitBreaker.
     *
     * @return the CircuitBreakerConfig of this CircuitBreaker
     */
    CircuitBreakerConfig getCircuitBreakerConfig();

    /**
     * States of the CircuitBreaker state machine.
     */
    enum State {
        /**
         * A CLOSED breaker is operating normally and allowing requests through.
         */
        CLOSED,
        /**
         * An OPEN breaker has tripped and will not allow requests through.
         */
        OPEN,
        /**
         * A HALF_OPEN breaker has completed its wait interval and will allow
         * requests
         */
        HALF_OPEN
    }

    interface Metrics {
        /**
         * Returns the failure rate in percentage. If the number of measured
         * calls is below the minimum number of measured calls, it returns -1.
         *
         * @return the failure rate in percentage
         */
        float getFailureRate();

        /**
         * Returns the current number of buffered calls.
         *
         * @return he current number of buffered calls
         */
        int getNumberOfBufferedCalls();

        /**
         * Returns the current number of failed calls.
         *
         * @return the current number of failed calls.
         */
        int getNumberOfFailedCalls();
    }
}
